23장 Claudia 살펴보기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 5가지만 1. Claudia(클로디아)는 클로드 코드에 "버튼이 보이는 화면"을 달아주는 무료 데스크톱 앱이라는 것 2. 클로디아를 설치하려면 공구 두 개(Rust, Bun)를 먼저 준비하고 빌드한다는 것 3. 자주 하는 일을 "에이전트" 버튼으로 저장해두고 한 번에 실행할 수 있다는 것 4. 지난 대화(세션)를 목록에서 골라 이어서 할 수 있다는 것 5. 토큰과 비용을 화면에서 한눈에 볼 수 있다는 것

이 장은 서드파티(외부 제작) 도구 소개입니다. 원서 작성 시점 기준 소개이며, 설치법·옵션·버전은 시간이 지나면 바뀝니다. 실제로 설치할 때는 클로디아 공식 저장소(github.com/getAsterisk/claudia)에서 최신 설치법을 꼭 확인하세요.

들어가기 전에 — 이런 적 있죠?

클로드 코드를 쓰다 보면 이런 순간이 옵니다.

터미널에 까만 화면만 떠 있는데, 지난번 대화를 다시 이어가려니 claude -r 같은 명령어가 가물가물합니다. 같은 프롬프트를 어제도 치고 오늘도 또 치고 있습니다. 이번 달에 토큰을 얼마나 썼는지 궁금한데, 어디서 봐야 하는지 모르겠습니다.

이게 바로 "CLI가 부담스럽다"는 느낌입니다. (CLI = 명령어를 글자로 쳐서 컴퓨터에 일을 시키는 방식. 일상 비유로는 "메뉴판 없이 외워서 주문하기"입니다. 앞 장들에서 우리가 계속 써온 그 까만 터미널 화면입니다.)

이 막막함을 풀어주는 게 이 장의 주인공, 클로디아입니다.

23-1 클로디아가 뭐예요?

학습목표

• 클로디아가 무엇을 하는 도구인지 설명한다.
• 클로디아와 클로드 코드의 관계를 구분한다.

비유부터

클로드 코드가 "문자로만 소통하는 비서"라면, 클로디아는 그 비서에게 "얼굴이 보이는 화상통화 앱"을 달아준 것입니다.

하는 일은 똑같습니다. 다만 명령어를 외워서 글자로 칠 필요 없이, 버튼을 눌러서 지시할 수 있으니 훨씬 직관적입니다.

또 다른 비유로는 이렇습니다. 클로드 코드가 "리모컨 없는 옛날 TV(다이얼을 직접 돌려야 함)"라면, 클로디아는 "리모컨"입니다. TV(클로드 코드)는 그대로인데, 조작을 편하게 해주는 도구가 하나 더 생긴 거죠.

비유를 클로디아에 연결하면

가장 중요한 한 가지

클로디아는 클로드 코드를 "대체"하는 게 아닙니다. 클로드 코드 "위에 얹는 화면(GUI)"입니다.

(GUI = Graphical User Interface. 버튼·아이콘·창으로 조작하는 화면 방식. 일상 비유로는 "터치스크린 키오스크"입니다. 글자를 외워 치는 CLI의 반대말이라고 생각하면 됩니다.)

그래서 클로디아에서 버튼을 눌러도, 실제 코드 작업은 뒤에서 클로드 코드가 합니다. 클로디아는 "안내 데스크 직원"이고, 실제 요리는 "주방(클로드 코드)"이 하는 셈이죠.

클로디아가 해결해주는 것 (잘못된 예 vs 올바른 예)

CLI만 쓸 때 vs 클로디아를 쓸 때를 비교해 봅니다.

지난 대화 이어가기 잘못 기억한 예: "어... claude -resume이었나? claude --r였나?" (헷갈려서 멈춤) 클로디아 방식: 세션 목록에서 원하는 대화 옆 [Resume] 버튼 클릭. 끝.

에이전트(자주 쓰는 작업) 실행 번거로운 예: 매번 긴 프롬프트를 통째로 다시 타이핑 클로디아 방식: Agents 탭에서 저장해둔 버튼 → [Run] 클릭

사용량 확인 막막한 예: "토큰 얼마 썼지? 어디서 보지?" 하고 인터넷을 뒤짐 클로디아 방식: Usage Dashboard 탭 클릭 → 바로 숫자가 보임

클로디아의 특징 다섯 가지

1. 화면(GUI) 제공 — 명령어 없이 마우스와 버튼으로 클로드 코드 조작
2. 에이전트 관리 — 자주 쓰는 작업을 저장해두고 버튼으로 반복 실행
3. 세션 관리 — 지난 대화를 눈으로 찾아서 이어가기
4. 사용량 추적 — 토큰·비용·모델별 통계를 한눈에 확인
5. 오픈소스(무료) — 커뮤니티가 만든 공개 프로젝트 (github.com/getAsterisk/claudia)

(오픈소스 = 소스 코드가 공개되어 누구나 보고 쓸 수 있는 무료 프로그램. 일상 비유로는 "누구나 따라 만들 수 있게 공개된 요리 레시피"입니다.)

한 걸음 더 ▸ 클로디아는 Tauri 2(타우리)라는 기술로 만들어졌습니다. Tauri = 데스크톱 앱을 가볍게 만드는 도구 틀. 일상 비유로는 "조립식 앱 키트"입니다. 지금은 "클로디아가 어떤 기술로 만들어졌구나" 정도만 알아도 충분합니다. 클로디아를 쓰는 데는 이 내용을 몰라도 됩니다.

체크포인트

• 클로디아는 클로드 코드를 대체하는 게 아니라 "위에 얹는 화면"이라는 걸 설명할 수 있나요?
• 버튼을 눌러도 실제 작업은 클로드 코드가 한다는 걸 구분할 수 있나요?

23-2 클로디아 설치하기

학습목표

• 클로디아 설치에 필요한 준비물을 설명한다.
• 설치 순서를 따라 한다.
• 설치가 막혔을 때 무엇부터 확인할지 구분한다.

비유부터

클로디아 설치는 "IKEA 가구 조립"과 비슷합니다.

먼저 공구를 준비하고 → 부품을 받고 → 설명서대로 조립하면 → 완성품이 나옵니다.

공구 = Rust와 Bun 부품 = 클로디아 코드 내려받기(git clone) 조립 = 빌드(build) 완성품 = 실행 파일

한 걸음 더 ▸ 두 공구가 뭐길래? Rust(러스트) = 프로그램의 속을 만드는 언어. 일상 비유로는 "튼튼한 골조용 철근". Bun(번) = 자바스크립트 부품들을 받아오고 묶어주는 도구. 일상 비유로는 "부품 배송 + 포장 담당". 둘 다 "왜 필요한지"는 몰라도 됩니다. 설치 순서만 따라 하면 됩니다.

설치 순서 (따라 하기)

설명에 나오는 버전·도구 이름은 원서/노트 기준 예시이며, 최신 값은 공식 문서에서 확인하세요. (도구 책은 버전이 자주 바뀝니다.)

1단계 — Rust 설치

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

원서 기준으로 Rust 1.70.0 이상이 필요합니다. (curl = 인터넷에서 파일을 받아오는 명령. 위 줄은 "Rust 설치 스크립트를 받아서 실행" 정도의 뜻입니다.)

2단계 — Bun 설치

curl -fsSL https://bun.sh/install | bash

원서 기준으로 최신 버전의 Bun이 필요합니다.

3단계 — 내 OS에 맞는 추가 도구 설치 (OS = 운영체제. 윈도우/맥/리눅스 같은 컴퓨터의 기본 시스템.)

맥(macOS)이라면:

xcode-select --install

필요하면 brew install pkg-config도 설치합니다.

윈도우(Windows)라면: "Microsoft C++ Build Tools"와 "WebView2"를 설치합니다. (WebView2 = 윈도우에서 앱 화면을 그려주는 부품. 일상 비유로는 "앱 안에 들어가는 작은 웹 브라우저". 윈도우에서는 이게 있어야 클로디아 화면이 뜹니다.)

4단계 — 클로디아 코드 받아서 폴더로 들어가기

git clone https://github.com/getAsterisk/claudia.git
cd claudia

5단계 — 부품(의존성) 설치

bun install

원서 예시에서는 패키지가 수백 개 설치됩니다. 잠깐 기다리면 됩니다.

6단계 — 빌드(조립)

bun run tauri build

7단계 — 만들어진 실행 파일 찾아 실행 빌드가 끝나면 OS별로 결과 폴더에 실행 파일이 생깁니다.

리눅스:  src-tauri/target/release/bundle/linux
맥:      src-tauri/target/release/bundle/macos
윈도우:  src-tauri/target/release/bundle/windows

OS별 준비물 한눈에

설치가 막혔을 때 — 미니 시나리오

상황: 6단계 bun run tauri build에서 빨간 에러가 났습니다. 당황하지 말고 아래 세 가지부터 순서대로 확인하세요.

1. Rust 버전 확인

rustc --version

1.70.0 이상인지 봅니다. 낮으면 다시 설치합니다.

1. OS별 추가 도구 확인 맥이면 Xcode CLI Tools, 윈도우면 WebView2와 MS C++ Build Tools가 설치돼 있는지 봅니다.

2. 부품 설치가 잘 됐는지 확인 bun install이 에러 없이 끝났는지 다시 봅니다. 중간에 빨간 글씨가 있었다면 거기가 원인일 수 있습니다.

체크포인트

• 클로디아 설치에 Rust와 Bun이 먼저 필요하다는 걸 설명할 수 있나요?
• 7단계 빌드 순서를 따라 할 수 있나요?
• 빌드 에러가 났을 때 무엇부터 볼지 구분할 수 있나요?

23-3 에이전트 기능 — 자주 쓰는 작업을 버튼으로

학습목표

• 에이전트가 무엇인지 설명한다.
• 에이전트를 만드는 순서를 따라 한다.
• "저장된 기본값"과 "실행할 때 입력"을 구분한다.

비유부터

매번 "Next.js 앱을 Tailwind랑 Shadcn UI로 만들어줘"라고 길게 타이핑한 적 있나요? 어제도 치고 오늘도 또 치고... 손가락이 아픕니다.

에이전트는 이런 반복을 없애주는 "매크로 버튼"입니다. (매크로 = 여러 번 할 일을 버튼 하나에 저장해두는 것. 일상 비유로는 "스마트폰의 즐겨찾기 단축 버튼".)

한 번 저장해두면, 다음부터는 "NextJS Creator" 버튼 하나만 누르면 같은 작업이 시작됩니다.

또 다른 비유로는 "라면 끓이는 레시피 카드"입니다. 끓이는 법(물 550ml, 4분 30초...)을 카드에 한 번 적어두면, 다음엔 카드만 보고 그대로 따라 하면 됩니다. 에이전트가 바로 그 "미리 적어둔 레시피 카드"입니다.

비유를 클로디아에 연결하면

에이전트는 무엇으로 이루어지나

에이전트 하나 = 이름 + 아이콘 + 모델 + System Prompt, 이 네 가지의 묶음입니다.

(System Prompt = 에이전트가 실행될 때마다 자동으로 주입되는 기본 지시문. 일상 비유로는 "직원에게 미리 붙여둔 업무 매뉴얼". 매번 설명 안 해도 알아서 그 규칙대로 일하게 만드는 글입니다.)

에이전트 만들기 (따라 하기)

[Agents 버튼] → [Create Agent] → 설정 입력 → [Save]

설정 항목은 이렇습니다.

① Agent Name : "NextJS Creator"
② Agent Icon : bot(로봇) 아이콘 선택
③ Model      : Claude 4 Sonnet 또는 Opus 선택
④ System Prompt :
   "NextJS 앱을 다음 기술스택으로 생성:
    - Tailwind CSS
    - Tanstack Table / Form
    - Shadcn UI"
⑤ [Save] 클릭

(모델 이름 Claude 4 Sonnet / Opus는 원서/노트 기준 예시입니다. 모델명은 시간이 지나면 바뀌므로, 최신 모델명은 공식 문서에서 확인하세요. 간단히는 Sonnet = 빠른 작업용, Opus = 복잡한 작업용 정도로 기억하면 됩니다.)

에이전트 실행하기 (따라 하기)

[Agents] → 에이전트 선택 → [Run] 클릭

그러면 실행 창이 뜹니다.

Execute: NextJS Creator
  Project Path : /Users/.../claudia_test  (작업할 폴더)
  Model        : Claude 4 Sonnet
  Task         : "쇼핑몰 사이트를 만들어줘"
  [▶ Execute]

[Execute]를 누르면, 뒤에서 클로드 코드가 실제 작업을 합니다. 클로디아는 버튼과 화면만 담당합니다. (23-1에서 본 "안내 데스크" 역할 그대로입니다.)

헷갈리기 쉬운 점 — 기본값 vs 실행 입력

잘못된 이해: "System Prompt에 다 적었으니 실행할 때는 아무것도 안 적어도 되겠지?" 올바른 이해: - System Prompt = 에이전트가 항상 지키는 기본 규칙 (레시피 카드) - Default Task = 실행 창에 미리 채워지는 기본 작업 (안 적으면 빈칸) - 실행할 때의 Task = 이번에 시킬 구체적인 일 ("쇼핑몰 사이트를 만들어줘")

즉, 규칙은 한 번 저장하고, 그때그때 할 일만 Task에 적어 넣는 구조입니다.

어떤 에이전트를 만들면 좋을까 (실무 예시)

체크포인트

• 에이전트 = 이름 + 모델 + System Prompt의 묶음이라는 걸 설명할 수 있나요?
• [Execute] 후 실제 작업은 클로드 코드가 한다는 걸 구분할 수 있나요?
• System Prompt(항상 지키는 규칙)와 Task(이번에 시킬 일)의 차이를 구분할 수 있나요?

23-4 세션 기능 — 지난 대화 이어가기

학습목표

• 세션이 무엇인지 설명한다.
• 새 세션을 만드는 순서를 따라 한다.
• 사고 단계(Thinking Token)가 토큰 소비와 어떻게 연결되는지 구분한다.

비유부터

CLI에서 지난 대화를 이어가는 건 "전화번호를 외워서 다시 걸기"와 같습니다. 어떤 대화였는지, 번호(세션 ID)가 뭐였는지 기억해야 하죠.

클로디아의 세션 기능은 "최근 통화 목록에서 터치해서 다시 걸기"와 같습니다. 목록에서 원하는 대화를 눈으로 찾아 누르면 끝입니다.

(세션 = 클로드 코드와 나눈 "한 묶음의 대화". 일상 비유로는 "카톡 대화방 하나". 새로 시작할 수도, 기존 방에 이어서 말할 수도 있습니다.)

비유를 클로디아에 연결하면

새 세션 만들기 (따라 하기)

[+ 버튼] → [New Claude Code Session]

그러면 설정 창이 뜹니다.

Claude Code Session
  Project Directory : /Users/.../test   (작업할 폴더 고르기)

  모델 선택:
    ⦿ Claude 4 Sonnet  (빠른 작업)
    ○ Claude 4 Opus    (복잡한 작업)

  Thinking Token 단계:
    Auto → Think → Think Hard → Think Harder → Ultrathink

  프롬프트 입력 → [실행하기]

새 세션을 만들 때는 (1) 작업할 폴더와 (2) 모델을 고르는 것부터 시작합니다.

Thinking Token이 뭐예요?

먼저 막혔던 장면부터. 간단한 일에는 답이 빨리 나오는데, 어려운 일은 클로드가 "잠깐 더 생각"해야 좋은 답이 나옵니다. 그 "생각하는 정도"를 우리가 조절할 수 있게 한 게 Thinking Token 단계입니다.

(Thinking Token = 클로드가 답하기 전에 "속으로 생각"하는 데 쓰는 토큰. 일상 비유로는 "문제 풀 때 끄적이는 연습장". 연습장을 많이 쓸수록 깊게 생각하지만, 그만큼 토큰(=비용)도 더 듭니다.)

단계는 다섯 개입니다. 위로 갈수록 더 깊게 생각하고, 토큰도 더 씁니다.

핵심 한 줄: 단계가 높을수록 더 똑똑하게 생각하지만, 토큰(비용)도 더 든다.

미니 시나리오 - 잘못된 선택: 오타 하나 고치는데 Ultrathink를 켬 → 토큰 낭비 - 올바른 선택: 오타 수정은 Auto나 Think, 큰 설계는 Think Harder 이상

지난 세션 이어가기 (Resume)

CLI 방식 vs 클로디아 방식을 비교해 봅니다.

CLI 방식:

claude -r

어떤 세션인지 머릿속으로 기억해야 합니다.

클로디아 방식:

CC Projects 화면 → 프로젝트 클릭 → 세션 리스트 확인 → [Resume] 클릭

세션 화면에서는 이런 것들을 볼 수 있습니다. - 지금 돌아가는 세션은 상단에 "Running" 표시 - 프로젝트별로 모든 세션이 리스트로 보임 - 각 세션의 첫 메시지, 시작 시간, 세션 ID 표시

덕분에 "그 대화가 뭐였더라" 하고 헤맬 일이 줄어듭니다.

체크포인트

• 새 세션을 만들 때 폴더와 모델을 먼저 고른다는 걸 설명할 수 있나요?
• Thinking Token 단계가 높을수록 토큰을 더 쓴다는 걸 구분할 수 있나요?
• 프로젝트를 누르면 그 프로젝트의 모든 세션 기록을 볼 수 있다는 걸 설명할 수 있나요?

23-5 사용량 확인 — 내가 얼마나 썼나

학습목표

• Usage Dashboard가 무엇을 보여주는지 설명한다.
• 네 가지 통계 관점을 구분한다.

비유부터

이번 달에 토큰을 얼마나 썼는지, 어디서 많이 썼는지 막막했던 적 있나요?

클로디아의 Usage Dashboard는 "통신사 요금 조회 앱"과 같습니다. 이번 달 데이터를 얼마나 썼는지, 어떤 앱에서 많이 썼는지, 지난달과 얼마나 차이 나는지 한 화면에 보여줍니다.

(Usage Dashboard = 토큰 사용량과 비용을 그림과 숫자로 보여주는 통계 화면. 일상 비유로는 "한 달 가계부 요약 화면".)

비유를 클로디아에 연결하면

Dashboard에서 볼 수 있는 것

Usage Dashboard
  전체 요약   : 총 토큰 사용량, API 비용(달러)
  모델별      : Sonnet은 얼마, Opus는 얼마
  프로젝트별  : 프로젝트 A는 얼마, B는 얼마
  세션별      : 세션 1은 얼마
  시계열      : 이번 달 vs 지난 달 비교

정리하면 네 가지 관점입니다: 모델별 · 프로젝트별 · 세션별 · 시계열.

어떻게 활용하나 (실무 미니 시나리오)

주의: 화면에 나오는 비용·토큰 숫자는 그때그때의 실제 사용량입니다. 또한 요금 체계 자체(가격·한도)는 원서/노트 기준이며 시간이 지나면 바뀌므로, 최신 요금은 공식 문서에서 확인하세요.

체크포인트

• Usage Dashboard에서 모델별·프로젝트별·세션별·시계열 네 가지 통계를 볼 수 있다는 걸 구분할 수 있나요?
• API를 쓸 때 비용을 추적할 수 있다는 걸 설명할 수 있나요?

CLI와 클로디아 한눈에 비교

(MCP = Model Context Protocol. 클로드 코드에 외부 도구를 연결해주는 표준 연결 방식. 일상 비유로는 "여러 가전을 꽂는 멀티탭". CLAUDE.md = 프로젝트마다 클로드 코드에게 주는 규칙·안내 파일. 앞 장들에서 다룬 그 파일입니다.)

한 줄 정리: 설치는 클로디아가 더 번거롭지만, 한번 깔고 나면 매일 쓰는 작업은 클로디아가 더 쉽습니다.

선수 지식 체크리스트

연습문제

연습문제 1 — 에이전트 설계

자신이 자주 하는 반복 작업 3가지를 에이전트로 설계해보세요. 각 에이전트의 이름, 모델(Sonnet/Opus), System Prompt를 적어보세요.

풀이 예시

에이전트 1: "README Generator"
- 모델: Claude 4 Sonnet
- System Prompt: "프로젝트 구조를 분석하고 README.md를 생성해줘.
  설치 방법, 사용 방법, API 문서를 포함해줘."

에이전트 2: "DB Schema Designer"
- 모델: Claude 4 Opus
- System Prompt: "요구사항을 분석하고 PostgreSQL 스키마를 설계해줘.
  ERD, 마이그레이션 파일, 시드 데이터를 포함해줘."

에이전트 3: "Performance Optimizer"
- 모델: Claude 4 Sonnet
- System Prompt: "코드의 성능 병목을 찾고 최적화 방안을 제시해줘.
  프로파일링 결과와 개선 전후 비교를 포함해줘."

(모델명은 예시입니다. 최신 모델명은 공식 문서에서 확인하세요.)

연습문제 2 — 설치 트러블슈팅

클로디아 설치 시 bun run tauri build에서 오류가 났다면, 가장 먼저 확인할 3가지는 무엇일까요?

풀이 예시

1. Rust 버전 확인: rustc --version 으로 1.70.0 이상인지 본다.
2. OS별 필수 도구 확인: 맥은 Xcode CLI Tools,
   윈도우는 WebView2와 MS C++ Build Tools가 있는지 본다.
3. 부품 설치 확인: bun install 이 에러 없이 끝났는지 다시 본다.

연습문제 3 — CLI vs 클로디아 비교

다음 작업을 CLI와 클로디아로 각각 어떻게 하는지 비교해보세요. (1) 이전 세션 이어가기 (2) 에이전트 실행 (3) 사용량 확인

풀이 예시 | 작업 | CLI | 클로디아 | |------|-----|----------| | 이전 세션 이어가기 | claude -r (또는 claude --resume) | CC Projects → 프로젝트 → 세션 → [Resume] | | 에이전트 실행 | 긴 프롬프트를 매번 타이핑 | Agents → 선택 → [Run] → [Execute] | | 사용량 확인 | 별도 웹사이트/대시보드 | Usage Dashboard 탭 클릭 |

용어 빠른 정리

참고자료

원서 작성 시점 기준 링크입니다. 설치·옵션은 각 공식 저장소에서 최신 내용을 확인하세요.

다음 장 예고: 다음 장에서는 또 다른 외부 도구를 살펴봅니다. 지금 그게 뭔지 몰라도 됩니다. 이 장에서 본 클로디아 다섯 가지만 손에 익혀도 충분합니다.